Skip to content

Add tsdoc package documentation#4711

Merged
raymondfeng merged 3 commits into
loopbackio:masterfrom
achrinzafork:docs/update-tsdocs
Apr 8, 2020
Merged

Add tsdoc package documentation#4711
raymondfeng merged 3 commits into
loopbackio:masterfrom
achrinzafork:docs/update-tsdocs

Conversation

@achrinza

@achrinza achrinza commented Feb 22, 2020 •
edited
Loading

Copy link
Copy Markdown
Member

Loosely related: #4697

This PR is part of a bigger incremental doc improvement.

As a starting point, the package documentation were, for the most part, copy-&-pasted from the respective README files.

Why this (and future tsdoc) PRs?

  1. Improve documentation
    • Improving the tsdocs would free up the main docs from having to state the fundamental purposes of each components.
    • The main docs can be updated to be more "guided" for new lb4 users.
    • The main docs can instead point readers to the tsdocs as reference.
  2. Improve reference docs
    • For those who need a quick reference point, the tsdocs can be useful.

Why this PR?
This PR fixes the emptiness this page:

image

  • ^ This page is usually the first page seen by users looking for a reference doc
  • Through this PR, the users will have a clearer idea on the purposes of the different packages.

Self-TODO

  • Add package docs for extensions
  • Check for errata
  • Fix code linting issues

Checklist

👉 Read and sign the CLA (Contributor License Agreement) 👈

  • npm test passes on your machine
  • New tests added or existing tests modified to cover all changes
  • Code conforms with the style guide
  • API Documentation in code was updated
  • Documentation in /docs/site was updated
  • Affected artifact templates in packages/cli were updated
  • Affected example projects in examples/* were updated

👉 Check out how to submit a PR 👈

@achrinza achrinza self-assigned this Feb 22, 2020
@achrinza achrinza added community-contribution developer-experience Issues affecting ease of use and overall experience of LB users Docs labels Feb 22, 2020
@achrinza
achrinza force-pushed the docs/update-tsdocs branch 3 times, most recently from 56cf5f3 to 05a9d6c Compare February 22, 2020 05:24
raymondfeng
raymondfeng reviewed Feb 22, 2020
View reviewed changes
Comment thread packages/authorization/src/index.ts Outdated
achrinza
achrinza commented Feb 22, 2020
View reviewed changes
Comment thread packages/context/src/index.ts Outdated
@achrinza
achrinza marked this pull request as ready for review February 22, 2020 13:43
@achrinza
achrinza requested a review from raymondfeng February 22, 2020 13:45
@raymondfeng

raymondfeng commented Feb 24, 2020

Copy link
Copy Markdown
Contributor

@achrinza Maybe it makes sense to squash all commits into one?

derdeka
derdeka requested changes Feb 24, 2020
View reviewed changes

@derdeka derdeka left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this PR, some high level comments.

  • You are mixing module, package and component for loopback packages which might be confusing.
  • Personally I like it more if the the tsdoc does not start with 'This module ...'.
  • (How to create a doc preview on windows?)

Comment thread packages/core/src/index.ts Outdated
Comment thread packages/core/src/index.ts Outdated
@achrinza

achrinza commented Feb 25, 2020

Copy link
Copy Markdown
Member Author

@raymondfeng Good idea, I've squashed all the add packageDocumentation into a stub commit.

@achrinza

achrinza commented Feb 25, 2020

Copy link
Copy Markdown
Member Author

@derdeka For the most part, these were copy&pasted from the READMEs. Though I agree, it should be consistent. I'll re-review and amend accordingly.

raymondfeng
raymondfeng reviewed Feb 25, 2020
View reviewed changes
Comment thread packages/tsdocs/src/index.ts
emonddr
emonddr suggested changes Mar 10, 2020
View reviewed changes

@emonddr emonddr left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good stuff, @achrinza .

Left one question for loopback-team.

Also please reduce the size of the commit message. thx

Comment thread packages/core/src/index.ts Outdated
@dhmlau

dhmlau commented Mar 27, 2020

Copy link
Copy Markdown
Member

@achrinza, could you please address feedback from @emonddr? Thanks.

@achrinza
achrinza force-pushed the docs/update-tsdocs branch 2 times, most recently from 4cd3807 to c1f8055 Compare March 28, 2020 07:51
@achrinza

achrinza commented Mar 28, 2020

Copy link
Copy Markdown
Member Author

@dhmlau Thanks for re-raising the issue, it slipped from my radar 🙇; I've applied the feedback. WDYT?

@dhmlau

dhmlau commented Mar 29, 2020

Copy link
Copy Markdown
Member

@achrinza, thanks. Could you please also take care of the commit linting error? Thanks!

@emonddr @raymondfeng @derdeka, may I get your review on this PR again please?

achrinza added 3 commits March 29, 2020 10:05
@achrinza
docs(tsdocs): fix 'LernaPackage' tsdoc typo
b2774d1 
Signed-off-by: Rifa Achrinza <25147899+achrinza@users.noreply.github.com>
@achrinza
docs(tsdocs): update packageDocumentation
aa113cd 
update packageDocumentation to follow tsdoc best practices

Signed-off-by: Rifa Achrinza <25147899+achrinza@users.noreply.github.com>
@achrinza
docs: add packageDocumentation
66a5169 
Signed-off-by: Rifa Achrinza <25147899+achrinza@users.noreply.github.com>
@achrinza
achrinza force-pushed the docs/update-tsdocs branch from c1f8055 to 66a5169 Compare March 29, 2020 02:06
@dhmlau dhmlau mentioned this pull request Apr 1, 2020
Closed
37 tasks
@dhmlau dhmlau added this to the April 2020 milestone Apr 1, 2020
@raymondfeng
raymondfeng merged commit 46e0bef into loopbackio:master Apr 8, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@raymondfeng raymondfeng raymondfeng approved these changes
@agnes512 agnes512 Awaiting requested review from agnes512
@bajtos bajtos Awaiting requested review from bajtos
@deepakrkris deepakrkris Awaiting requested review from deepakrkris
@hacksparrow hacksparrow Awaiting requested review from hacksparrow
@jannyHou jannyHou Awaiting requested review from jannyHou
@nabdelgadir nabdelgadir Awaiting requested review from nabdelgadir nabdelgadir is a code owner
@derdeka derdeka Awaiting requested review from derdeka
+1 more reviewer
@emonddr emonddr emonddr requested changes
Reviewers whose approvals may not affect merge requirements

Assignees

@achrinza achrinza

Labels

developer-experience Issues affecting ease of use and overall experience of LB users Docs

Projects

None yet

Milestone

April 2020

Development

Successfully merging this pull request may close these issues.

5 participants

@achrinza @raymondfeng @dhmlau @emonddr @derdeka